<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <link rel="stylesheet" href="http://www.petercorke.com/RVC/common/toolboxhelp.css">
    <title>M-File Help: Quaternion</title>
  </head>
  <body>
  <table border="0" cellspacing="0" width="100%">
    <tr class="subheader">
      <td class="headertitle">M-File Help: Quaternion</td>
      <td class="subheader-left"><a href="matlab:open Quaternion">View code for Quaternion</a></td>
    </tr>
  </table>
<h1>Quaternion</h1><p><span class="helptopic">Quaternion class</span></p><p>
A quaternion is 4-element mathematical object comprising a scalar s, and
a vector v and is typically written: q = s &amp;lt;&amp;lt;vx, vy, vz&amp;gt;&amp;gt;.

</p>
<p>
A quaternion of unit length can be used to represent 3D orientation and
is implemented by the subclass UnitQuaternion.

</p>
<h2>Constructors</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> Quaternion</td> <td>general constructor</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> Quaternion.pure</td> <td>pure quaternion</td></tr>
</table>
<h2>Display methods</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> display</td> <td>print in human readable form</td></tr>
</table>
<h2>Operation methods</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> inv</td> <td>inverse</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> conj</td> <td>conjugate</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> norm</td> <td>norm, or length</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> unit</td> <td>unitized quaternion</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> inner</td> <td>inner product</td></tr>
</table>
<h2>Conversion methods</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> char</td> <td>convert to string</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> double</td> <td>quaternion elements as 4-vector</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> matrix</td> <td>quaternion as a 4x4 matrix</td></tr>
</table>
<h2>Overloaded operators</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> q*q2</td> <td>quaternion (Hamilton) product</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> s*q</td> <td>elementwise multiplication of quaternion by scalar</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> q/q2</td> <td>q*q2.inv</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> q^n</td> <td>q to power n (integer only)</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> q+q2</td> <td>elementwise sum of quaternion elements</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> q-q2</td> <td>elementwise difference of quaternion elements</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> q1==q2</td> <td>test for quaternion equality</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> q1~=q2</td> <td>test for quaternion inequalityq = rx*ry*rz;</td></tr>
</table>
<h2>Properties (read only)</h2>
<table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> s </td> <td>real part</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> v </td> <td>vector part</td></tr>
</table>
<h2>Notes</h2>
<ul>
  <li>Quaternion objects can be used in vectors and arrays.</li>
</ul>
<h2>References</h2>
<ul>
  <li>Animating rotation with quaternion curves,
K. Shoemake,
in Proceedings of ACM SIGGRAPH, (San Fran cisco), pp. 245-254, 1985.</li>
  <li>On homogeneous transforms, quaternions, and computational efficiency,
J. Funda, R. Taylor, and R. Paul,
IEEE Transactions on Robotics and Automation, vol. 6, pp. 382-388, June 1990.</li>
  <li>Robotics, Vision & Control,
P. Corke, Springer 2011.</li>
</ul>
<h2>See also</h2>
<p>
<a href="UnitQuaternion.html">UnitQuaternion</a></p>
<hr>
<a name="Quaternion"><h1>Quaternion.Quaternion</h1></a>
<p><span class="helptopic">Construct a quaternion object</span></p><p>
Q = <span style="color:red">Quaternion</span> is a zero quaternion

</p>
<p>
Q = <span style="color:red">Quaternion</span>([S V1 V2 V3]) is a quaternion formed by specifying directly its 4 elements

</p>
<p>
<strong>q</strong> = <span style="color:red">Quaternion</span>(<strong>s</strong>, <strong>v</strong>) is a quaternion formed from the scalar <strong>s</strong> and vector
part <strong>v</strong> (1x3)

</p>
<h2>Notes</h2>
<ul>
  <li>The constructor is not vectorized, it cannot create a vector of
Quaternions.</li>
</ul>
<hr>
<a name="char"><h1>Quaternion.char</h1></a>
<p><span class="helptopic">Convert to string</span></p><p>
<strong>s</strong> = Q.<span style="color:red">char</span>() is a compact string representation of the quaternion's value
as a 4-tuple.  If Q is a vector then <strong>s</strong> has one line per element.

</p>
<hr>
<a name="conj"><h1>Quaternion.conj</h1></a>
<p><span class="helptopic">Conjugate of a quaternion</span></p><p>
<strong>qi</strong> = Q.<span style="color:red">conj</span>() is a quaternion object representing the conjugate of Q.

</p>
<h2>Notes</h2>
<ul>
  <li>Conjugatation changes the sign of the vector component.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.inv.html">Quaternion.inv</a></p>
<hr>
<a name="display"><h1>Quaternion.display</h1></a>
<p><span class="helptopic">Display quaternion</span></p><p>
Q.<span style="color:red">display</span>() displays a compact string representation of the quaternion's value
as a 4-tuple.  If Q is a vector then S has one line per element.

</p>
<h2>Notes</h2>
<ul>
  <li>This method is invoked implicitly at the command line when the result
of an expression is a Quaternion object and the command has no trailing
semicolon.</li>
  <li>The vector part is displayed with double brackets << 1, 0, 0 >> to
distinguish it from a UnitQuaternion which displays as < 1, 0, 0 ></li>
  <li>If Q is a vector of Quaternion objects the elements are displayed on
consecutive lines.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.char.html">Quaternion.char</a></p>
<hr>
<a name="double"><h1>Quaternion.double</h1></a>
<p><span class="helptopic">Convert a quaternion to a 4-element vector</span></p><p>
<strong>v</strong> = Q.<span style="color:red">double</span>() is a row vector (1x4) comprising the quaternion elements,
scalar then vector.  If Q is a vector (1xN) of <span style="color:red">Quaternion</span> objects then <strong>v</strong> is a
matrix (Nx4) with rows corresponding to the <span style="color:red">Quaternion</span> elements.

</p>
<p>
elements [s vx vy vz].

</p>
<hr>
<a name="eq"><h1>Quaternion.eq</h1></a>
<p><span class="helptopic">Test quaternion equality</span></p><p>
Q1==Q2 is true if the quaternions Q1 and Q2 are equal.

</p>
<h2>Notes</h2>
<ul>
  <li>Overloaded operator '=='.</li>
  <li>This method is invoked for unit Quaternions where Q and -Q represent
the equivalent rotation, so non-equality does not mean rotations are not
equivalent.</li>
  <li>If Q1 is a vector of quaternions, each element is compared to
Q2 and the result is a logical array of the same length as Q1.</li>
  <li>If Q2 is a vector of quaternions, each element is compared to
Q1 and the result is a logical array of the same length as Q2.</li>
  <li>If Q1 and Q2 are vectors of the same length, then the result
is a logical array of the same length.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.ne.html">Quaternion.ne</a></p>
<hr>
<a name="inner"><h1>Quaternion.inner</h1></a>
<p><span class="helptopic">Quaternion inner product</span></p><p>
<strong>v</strong> = Q1.<span style="color:red">inner</span>(<strong>q2</strong>) is the <span style="color:red">inner</span> (dot) product of two vectors (1x4),
comprising the elements of Q1 and <strong>q2</strong> respectively.

</p>
<h2>Notes</h2>
<ul>
  <li>Q1.inner(Q1) is the same as Q1.norm().</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.norm.html">Quaternion.norm</a></p>
<hr>
<a name="inv"><h1>Quaternion.inv</h1></a>
<p><span class="helptopic">Invert a quaternion</span></p><p>
<strong>qi</strong> = Q.<span style="color:red">inv</span>() is a quaternion object representing the inverse of Q.

</p>
<h2>Notes</h2>
<ul>
  <li>Is vectorized.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.conj.html">Quaternion.conj</a></p>
<hr>
<a name="isequal"><h1>Quaternion.isequal</h1></a>
<p><span class="helptopic">Test quaternion element equality</span></p><p>
<span style="color:red">ISEQUAL</span>(<strong>q1</strong>,<strong>q2</strong>) is true if the quaternions <strong>q1</strong> and <strong>q2</strong> are equal.

</p>
<h2>Notes</h2>
<ul>
  <li>Used by test suite verifyEqual in addition to eq().</li>
  <li>Invokes eq().</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.eq.html">Quaternion.eq</a></p>
<hr>
<a name="matrix"><h1>Quaternion.matrix</h1></a>
<p><span class="helptopic">Matrix representation of Quaternion</span></p><p>
<strong>m</strong> = Q.<span style="color:red">matrix</span>() is a <span style="color:red">matrix</span> (4x4) representation of the <span style="color:red">Quaternion</span> Q.

</p>
<p>
<span style="color:red">Quaternion</span>, or Hamilton, multiplication can be implemented as a
<span style="color:red">matrix</span>-vector product, where the column-vector is the elements of a
second quaternion:

</p>
<pre style="width: 90%%;" class="examples">
matrix(Q1)&nbsp;*&nbsp;double(Q2)'
</pre>
<h2>Notes</h2>
<ul>
  <li>This matrix is not unique, other matrices will serve the purpose for
multiplication, see https://en.wikipedia.org/wiki/Quaternion#Matrix_representations</li>
  <li>The determinant of the matrix is the norm of the quaternion to the fourth power.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.double.html">Quaternion.double</a>, <a href="Quaternion.mtimes.html">Quaternion.mtimes</a></p>
<hr>
<a name="minus"><h1>Quaternion.minus</h1></a>
<p><span class="helptopic">Subtract quaternions</span></p><p>
Q1-Q2 is a <span style="color:red">Quaternion</span> formed from the element-wise difference of quaternion elements.

</p>
<p>
Q1-V  is a <span style="color:red">Quaternion</span> formed from the element-wise difference of Q1 and the
vector V (1x4).

</p>
<h2>Notes</h2>
<ul>
  <li>Overloaded operator '-'</li>
  <li>This is not a group operator, but it is useful to have the result as a
quaternion.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.plus.html">Quaternion.plus</a></p>
<hr>
<a name="mpower"><h1>Quaternion.mpower</h1></a>
<p><span class="helptopic">Raise quaternion to integer power</span></p><p>
Q&circ;N is the <span style="color:red">Quaternion</span> Q raised to the integer power N.

</p>
<h2>Notes</h2>
<ul>
  <li>Overloaded operator '^'</li>
  <li>Computed by repeated multiplication.</li>
  <li>If the argument is a unit-quaternion, the result will be a
unit quaternion.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.mtimes.html">Quaternion.mtimes</a></p>
<hr>
<a name="mrdivide"><h1>Quaternion.mrdivide</h1></a>
<p><span class="helptopic">Quaternion quotient.</span></p><table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> Q1/Q2</td> <td>is a quaternion formed by Hamilton product of Q1 and inv(Q2).</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> Q/S</td> <td>is the element-wise division of quaternion elements by the scalar S.</td></tr>
</table>
<h2>Notes</h2>
<ul>
  <li>Overloaded operator '/'</li>
  <li>For case Q1/Q2 both can be an N-vector, result is elementwise
division.</li>
  <li>For case Q1/Q2 if Q1 scalar and Q2 a vector, scalar is divided by each
element.</li>
  <li>For case Q1/Q2 if Q2 scalar and Q1 a vector, each element divided by
scalar.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.mtimes.html">Quaternion.mtimes</a>, <a href="Quaternion.mpower.html">Quaternion.mpower</a>, <a href="Quaternion.plus.html">Quaternion.plus</a>, <a href="Quaternion.minus.html">Quaternion.minus</a></p>
<hr>
<a name="mtimes"><h1>Quaternion.mtimes</h1></a>
<p><span class="helptopic">Multiply a quaternion object</span></p><table class="list">
  <tr><td style="white-space: nowrap;" class="col1"> Q1*Q2</td> <td>is a quaternion formed by the Hamilton product of two quaternions.</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> Q*S</td> <td>is the element-wise multiplication of quaternion elements by the scalar S.</td></tr>
  <tr><td style="white-space: nowrap;" class="col1"> S*Q</td> <td>is the element-wise multiplication of quaternion elements by the scalar S.</td></tr>
</table>
<h2>Notes</h2>
<ul>
  <li>Overloaded operator '*'</li>
  <li>For case Q1*Q2 both can be an N-vector, result is elementwise
multiplication.</li>
  <li>For case Q1*Q2 if Q1 scalar and Q2 a vector, scalar multiplies each
element.</li>
  <li>For case Q1*Q2 if Q2 scalar and Q1 a vector, each element multiplies
scalar.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.mrdivide.html">Quaternion.mrdivide</a>, <a href="Quaternion.mpower.html">Quaternion.mpower</a></p>
<hr>
<a name="ne"><h1>Quaternion.ne</h1></a>
<p><span class="helptopic">Test quaternion inequality</span></p><p>
Q1 ~= Q2 is true if the quaternions Q1 and Q2 are not equal.

</p>
<h2>Notes</h2>
<ul>
  <li>Overloaded operator '~='</li>
  <li>Note that for unit Quaternions Q and -Q are the equivalent
rotation, so non-equality does not mean rotations are not
equivalent.</li>
  <li>If Q1 is a vector of quaternions, each element is compared to
Q2 and the result is a logical array of the same length as Q1.</li>
  <li>If Q2 is a vector of quaternions, each element is compared to
Q1 and the result is a logical array of the same length as Q2.</li>
  <li>If Q1 and Q2 are vectors of the same length, then the result
is a logical array of the same length.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.eq.html">Quaternion.eq</a></p>
<hr>
<a name="new"><h1>Quaternion.new</h1></a>
<p><span class="helptopic">Construct a new quaternion</span></p><p>
<strong>qn</strong> = Q.<span style="color:red">new</span>() constructs a <span style="color:red">new</span> <span style="color:red">Quaternion</span> object of the same type as Q.

</p>
<p>
<strong>qn</strong> = Q.<span style="color:red">new</span>([S V1 V2 V3]) as above but specified directly by its 4 elements.

</p>
<p>
<strong>qn</strong> = Q.<span style="color:red">new</span>(<strong>s</strong>, <strong>v</strong>) as above but specified directly by the scalar <strong>s</strong> and vector
part <strong>v</strong> (1x3)

</p>
<h2>Notes</h2>
<ul>
  <li>Polymorphic with UnitQuaternion and RTBPose derived classes.</li>
</ul>
<hr>
<a name="norm"><h1>Quaternion.norm</h1></a>
<p><span class="helptopic">Quaternion magnitude</span></p><p>
<strong>qn</strong> = <strong>q</strong>.<span style="color:red">norm</span>(<strong>q</strong>) is the scalar <span style="color:red">norm</span> or magnitude of the quaternion <strong>q</strong>.

</p>
<h2>Notes</h2>
<ul>
  <li>This is the Euclidean norm of the quaternion written as a 4-vector.</li>
  <li>A unit-quaternion has a norm of one.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.inner.html">Quaternion.inner</a>, <a href="Quaternion.unit.html">Quaternion.unit</a></p>
<hr>
<a name="plus"><h1>Quaternion.plus</h1></a>
<p><span class="helptopic">Add quaternions</span></p><p>
Q1+Q2 is a <span style="color:red">Quaternion</span> formed from the element-wise sum of quaternion elements.

</p>
<p>
Q1+V  is a <span style="color:red">Quaternion</span> formed from the element-wise sum of Q1 and the
vector V (1x4).

</p>
<h2>Notes</h2>
<ul>
  <li>Overloaded operator '+'</li>
  <li>This is not a group operator, but it is useful to have the result as a
quaternion.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.minus.html">Quaternion.minus</a></p>
<hr>
<a name="pure"><h1>Quaternion.pure</h1></a>
<p><span class="helptopic">Construct a pure quaternion</span></p><p>
<strong>q</strong> = <span style="color:red">Quaternion</span>.<span style="color:red">pure</span>(<strong>v</strong>) is a <span style="color:red">pure</span> quaternion formed from the vector <strong>v</strong> (1x3) and has
a zero scalar part.

</p>
<hr>
<a name="set.s"><h1>Quaternion.set.s</h1></a>
<p><span class="helptopic">Set scalar component</span></p><p>
Q.s = S sets the scalar part of the <span style="color:red">Quaternion</span> object to S.

</p>
<hr>
<a name="set.v"><h1>Quaternion.set.v</h1></a>
<p><span class="helptopic">Set vector component</span></p><p>
Q.v = V sets the vector part of the <span style="color:red">Quaternion</span> object to V (1x3).

</p>
<hr>
<a name="unit"><h1>Quaternion.unit</h1></a>
<p><span class="helptopic">Unitize a quaternion</span></p><p>
<strong>qu</strong> = Q.<span style="color:red">unit</span>() is a UnitQuaternion object representing the same orientation as Q.

</p>
<h2>Notes</h2>
<ul>
  <li>Is vectorized.</li>
</ul>
<h2>See also</h2>
<p>
<a href="Quaternion.norm.html">Quaternion.norm</a>, <a href="UnitQuaternion.html">UnitQuaternion</a></p>
<hr>

<table border="0" width="100%" cellpadding="0" cellspacing="0">
  <tr class="subheader" valign="top"><td>&nbsp;</td></tr></table>
<p class="copy">&copy; 1990-2014 Peter Corke.</p>
</body></html>